home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / bbs / doorinfo.zip / FOSSIL.DOC < prev    next >
Text File  |  1997-05-14  |  36KB  |  843 lines
  1. Note to Falken Door Writers -
  2. The following document describes FOSSIL services.  It has not been
  3. edited in any way.  Be aware, however, that Falken only implements
  4. those services dealing directly with the serial port.  The screen I/O
  5. functions, timer interrupt functions, etc. are not supported by
  6. Falken.
  7.  
  8. The FOSSIL driver is internal to Falken.  It is not necessary to
  9. load an external FOSSIL driver when Falken is running.
  10.  
  11.                                                     Herb Rose
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.                  Fundamentals of FOSSIL implementation and use
  25.                         Version 5,  February 11,  1988
  26.                        Rick Moore,  Solar Wind Computing
  27.  
  28.  
  29.           FidoNet Address: Zone 1,  Network 115,  Node 333 (1:115/333)
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  Copyright (C) 1987, VEP Software, Naugatuck, CT 06770. All rights reserved.
  59.  Copyright (C) 1988, Rick Moore,  Homewood,  IL, 60430. All rights reserved.
  60.  
  61.  This document may be freely used or copied by anyone interested in the data
  62.  contained herein. No fees may be charged for distribution of this document.
  63.  You will be held  accountable for all such charges,  and expected to either
  64.  reimburse those persons or organizations so charged,  or to make a donation
  65.  in the exact amount of those fees to the International FidoNet Association,
  66.  to  assist  them in their  efforts to  advance the  technology of  personal
  67.  computer telecommunications.
  68.  
  69. Fundamentals of FOSSIL implementation and use                         Page 2
  70. Introduction
  71.  
  72.  
  73.  
  74.  A. Objectives of this document
  75.  
  76.     This document is directed at implementors or intellectuals.  It is meant
  77.     for use in implementing applications that can use FOSSIL drivers, or for
  78.     details needed to implement a new FOSSIL. As such it won't always go out
  79.     of its way to explain itself to the neophyte.
  80.  
  81.     This document will have served its purpose to you if you are able to use
  82.     the data contained within to perform either of the above tasks.   If you
  83.     feel  that necessary  data has  been omitted  please contact  Rick Moore
  84.     at the above listed address so that the  appropriate changes can be made.
  85.     Any lines changed in the current version are marked with "|" in the left
  86.     margin.
  87.  
  88.  
  89.  B. Historical perspective
  90.  
  91.     For those people who were not lucky enough to have an IBM PC or a system
  92.     nearly completely compatible, the world has not been very friendly. With
  93.     his implementation of the Generic Fido(tm) driver,  Tom Jennings made it
  94.     possible for systems that had nothing in common with an IBM PC except an
  95.     808x-class processor, and the ability to run MS-DOS Version 2 and above,
  96.     to run his Fido(tm) software. That was a lot to ask, and a lot of people
  97.     thought it was enough.
  98.  
  99.     But not everyone.  While Thom Henderson was debugging Version 4.0 of his
  100.     SEAdog(tm) mail package,  an "extended" Generic driver was designed  (in
  101.     cooperation with Bob Hartman)   as a quick kludge to help him get past a
  102.     problem with certain UART chips.The new hook was quickly pounced upon by
  103.     Vince Perriello,  who, with almost DAILY prodding (ouch! it still hurts)
  104.     by Ken Kaplan,had been working with Henderson to get DEC Rainbow support
  105.     into SEAdog. Vince then coded a driver to use this hook and - Voila! -
  106.     SEAdog 4.0 started working like a champ on the Rainbow.
  107.  
  108.     At the same time something was rotten in the state of Texas. Wynn Wagner
  109.     started  encountering some serious  difficulties in his Opus development
  110.     effort. Specifically, he couldn't force the Greenleaf(tm) Communications
  111.     Libraries to behave in exactly the way he felt Opus required.  Enter Bob
  112.     Hartman.Having already enjoyed success in the effort with Thom Henderson,
  113.     he suggested to Wynn that with very few extensions,  any driver that was
  114.     already  SEAdog(tm) 4.0 compatible could drive Opus as well.  About that
  115.     time, Vince called Wynn to discuss porting Opus to the DEC Rainbow. Wynn
  116.     called Bob, Bob called Vince, and the FOSSIL driver came into existence.
  117.  
  118.     FOSSIL is an acronym for "Fido/Opus/SEAdog Standard Interface Layer". To
  119.     say that the concept has gained wide acceptance in the FidoNet community
  120.     would be an understatement. Henk Wevers' DUTCHIE package uses the FOSSIL
  121.     communications services.   Ron Bemis' OUTER package uses FOSSIL services
  122.     for everything it does and as a result it is completely generic.   There
  123.     are already FOSSIL implementations for the Tandy 2000, Heath/Zenith 100,
  124.     Sanyo 555 and other "non-IBM" architectures. With each new 'port' of the
  125.     spec, the potential of a properly coded FOSSIL application grows!
  126.  
  127. Fundamentals of FOSSIL implementation and use                         Page 3
  128. Basic conventions and calling method
  129.  
  130.  
  131.  
  132.  C. Basic principles of a FOSSIL driver
  133.  
  134.     1)  Interrupt 14h.
  135.  
  136.     The one basic rule that the driver depends upon,  is the ability for ANY
  137.     target machine to allow the vector for INT 14h (usually pointing to BIOS
  138.     comm functions) to be "stolen" by the driver.  In a system where the INT
  139.     14h vector is used already, it must be possible to replace the "builtin"
  140.     functionality with that of a FOSSIL,  when an application that wants the
  141.     use of a FOSSIL is to be run on the target machine.
  142.  
  143.  
  144.     2)  How to install a FOSSIL driver in a system
  145.  
  146.     There's no hard and fast way to do this. The FOSSIL might be implemented
  147.     as part of a device driver (like Ray Gwinn's X00.SYS) and therefore gets
  148.     loaded using a line in CONFIG.SYS at bootup time.  It might be done as a
  149.     TSR (terminate and stay resident) program, in which event you install it
  150.     by running the program  (DECcomm by Vince Perriello and Opus!Comm by Bob
  151.     Hartman work this way, for example).
  152.  
  153.  
  154.     3)  How an application can detect the presence of a FOSSIL
  155.  
  156.     The driver has a "signature" that can be used to determine whether it is
  157.     present in memory. At offset 6 in the INT 14h service routine is a word,
  158.     1954h,  followed  by a  byte that  specifies the maximum function number
  159.     supported by the driver. This is to make it possible to determine when a
  160.     driver is present and what level of functionality it provides. Also, the
  161.     Init call (see below)  returns a 1954h  in AX.  SEAdog(tm)  looks at the
  162.     signature and Opus just goes for the Init. Fido doesn't do either.
  163.  
  164.  
  165.     4)  How to call a FOSSIL function
  166.  
  167.     The FOSSIL driver  is entered  by issuing  a software Interrupt 14h from
  168.     the application  program. The code corresponding to the desired function
  169.     should be in 8-bit register AH. For calls that relate to communications,
  170.     the port number will be passed from the application in register DX. When
  171.     DX contains a zero (0) it signifies use of COM1, or whatever the "first"
  172.     serial port on your machine is called. A one (1) in DX points the driver
  173.     at COM2, and so on.  A value of 00FFh in DX is considered a special case
  174.     where the driver  should do no actual processing but return SUCCESS.  In
  175.     the specific case of Init/Uninit with DX=00FFh,the FOSSIL should perform
  176.     all non-communications  processing  necessary  with such calls.  In some
  177.     machines  (H/Z-100 for example),  the FOSSIL must  assume control of the
  178.     keyboard in order to service the keyboard functions.
  179.  
  180.     FOR ALL FUNCTIONS,  ALL REGISTERS NOT SPECIFICALLY CONTAINING A FUNCTION
  181.     RETURN VALUE MUST BE PRESERVED ACROSS THE CALL.
  182.  
  183. Fundamentals of FOSSIL implementation and use                         Page 4
  184. Communications functions
  185.  
  186.  
  187. D. Functions currently defined for FOSSILs
  188.  
  189.  
  190.     AH = 00h    Set baud rate
  191.  
  192.             Parameters:
  193.                 Entry:  AL = Baud rate code
  194.                         DX = Port number
  195. |               Exit:   AX = Port status (see function 03h)
  196.  
  197.     This works the same as the  equivalent IBM PC BIOS call,  except that it
  198.     ONLY selects a baud rate.  This is passed in the high order 3 bits of AL
  199.     as follows:
  200.  
  201.                 010 =   300 baud
  202.                 011 =   600  ''
  203.                 100 =  1200  ''
  204.                 101 =  2400  ''
  205.                 110 =  4800  ''
  206.                 111 =  9600  ''
  207.                 000 = 19200  '' (Replaces old 110 baud mask)
  208.                 001 = 38400  '' (Replaces old 150 baud mask)
  209.  
  210.     The low order 5 bits can be implemented or not by the FOSSIL, but in all
  211.     cases, if the low order bits of AL are 00011,  the result should be that
  212.     the communications device should be set to eight data bits, one stop bit
  213.     and no parity. This setting is a  MINIMUM REQUIREMENT  of Fido, Opus and
  214.     SEAdog.  For purposes of completeness,  here are the IBM PC "compatible"
  215.     bit settings:
  216.  
  217.     Bits 4-3 define parity:     0 0       no parity
  218.                                 1 0       no parity
  219.                                 0 1      odd parity
  220.                                 1 1     even parity
  221.  
  222.     Bit 2 defines stop bits:      0        1 stop bit;
  223.                                   1      1.5 bits for 5-bit char;
  224.                                            2 for others
  225.  
  226.     Bits 1-0 character length:  0 0        5 bits
  227.                                 0 1        6 bits
  228.                                 1 0        7 bits
  229.                                 1 1        8 bits
  230.  
  231. Fundamentals of FOSSIL implementation and use                         Page 5
  232. Communications functions
  233.  
  234.  
  235.     AH = 01h    Transmit character with wait
  236.  
  237.             Parameters:
  238.                 Entry:  AL = Character
  239.                         DX = Port number
  240.                 Exit:   AX = Port status (see function 03h)
  241.  
  242.     AL contains the character to be sent.   If there is room in the transmit
  243.     buffer the return will be immediate,  otherwise it will wait until there
  244.     is room to store the character in the transmit buffer.  On return, AX is
  245.     set as in a status request (see function 03h).
  246.  
  247.  
  248.     AH = 02h    Receive character with wait
  249.  
  250.             Parameters:
  251.                 Entry:  DX = Port number
  252.                 Exit:   AH = 00h
  253.                         AL = Input character
  254.  
  255.     If there is a character  available in the  receive buffer,  returns with
  256.     the next character in AL.  It will wait until a character is received if
  257.     none is available.
  258.  
  259.  
  260.     AH = 03h    Request status
  261.  
  262.             Parameters:
  263.                 Entry:  DX = Port number
  264.                 Exit:   AX = Status bit mask (see below)
  265.  
  266.     Returns with the line and modem status in AX.  Status bits returned are:
  267.  
  268.             In AH:
  269.                 Bit 0 = RDA  - input data is available in buffer
  270. |               Bit 1 = OVRN - the input buffer has been overrun.  All
  271. |                              characters received after the buffer is
  272. |                              full should be discarded.
  273.                 Bit 5 = THRE - room is available in output buffer
  274.                 Bit 6 = TSRE - output buffer is empty
  275.  
  276.             In AL:
  277. |               Bit 3 = Always 1 (always return with this bit set to 1)
  278.                 Bit 7 = DCD  - carrier detect
  279.  
  280.     This can be used by the application to determine  whether carrier detect
  281.     (CD) is set,  signifying the presence/absence of a remote connection, as
  282.     well as monitoring both the input and output buffer status.  Bit 3 of AL
  283.     is always returned set to enable programs to use it as a carrier detect
  284.     bit on hardwired (null modem) links.
  285.  
  286. Fundamentals of FOSSIL implementation and use                         Page 6
  287. Communications functions
  288.  
  289.  
  290.     AH = 04h    Initialize driver
  291.  
  292.             Parameters:
  293.                 Entry:  DX = port number
  294.                       ( BX = 4F50h
  295. |                       ES:CX = ^C flag address --- optional )
  296.                 Exit:   AX = 1954h if successful
  297. |                       BL = maximum function number supported
  298. |                            (not counting functions 7Eh and above)
  299. |                       BH = rev of FOSSIL doc supported
  300.  
  301.     This is used to tell the driver to begin  operations,  and to check that
  302.     the driver is installed. This function should be called before any other
  303.     communications calls are made.  At this point all interrupts involved in
  304.     supporting the comm port (specified in DX) should be set up for handling
  305.     by  the  FOSSIL, then  enabled.  If BX contains 4F50h,  then the address
  306.     specified in ES:CX is that of a ^C flag byte in the application program,
  307.     to be incremented when  ^C is detected in the keyboard service routines.
  308.     This is an optional service and only need be supported on machines where
  309.     the keyboard service can't (or won't) perform an INT 1Bh or INT 23h when
  310. |   a Control-C is entered.  DTR is raised by this call.  The baud rate must
  311. |   NOT be changed by this call.
  312.  
  313.     NOTE: Should an additional call to this service occur  (2 Inits or Init,
  314.     Read,Init, etc.) the driver should reset all buffers, flow control, etc.
  315.     to the INIT state and return SUCCESS.
  316.  
  317.  
  318.     AH = 05h    Deinitialize driver
  319.  
  320.             Parameters:
  321.                 Entry:  DX = Port number
  322.                 Exit:   None
  323.  
  324.     This is used to tell the driver that comm port operations are ended. The
  325.     function should be called  when no more comm port functions will be used
  326.     on the port specified in DX.  DTR is NOT affected by this call.
  327.  
  328.  
  329.     AH = 06h    Raise/lower DTR
  330.  
  331.             Parameters:
  332.                 Entry:  DX = Port number
  333.                         AL = DTR state to be set (01h = Raise, 00h = Lower)
  334.                 Exit:   None
  335.  
  336.     This function is used to control the DTR line to the modem. AL = 00h means
  337.     lower DTR (disable the modem), and AL = 01h means to raise DTR (enable the
  338.     modem).  No other function (except Init) should alter DTR.
  339.  
  340. Fundamentals of FOSSIL implementation and use                         Page 7
  341. Communications functions
  342.  
  343.  
  344.     AH = 07h    Return timer tick parameters
  345.  
  346.             Parameters:
  347.                 Entry:  None
  348.                 Exit:   AL = Timer tick interrupt number
  349.                         AH = Ticks per second on interrupt number in AL
  350.                         DX = Approximate number of milliseconds per tick
  351.  
  352.     This is used to  determine the parameters of the timer tick on any given
  353.     machine.  Three numbers are returned:
  354.  
  355.         AL =   Timer tick interrupt number
  356.         AH =   Ticks per second on interrupt number shown in AL
  357.         DX =   Milliseconds per tick (approximate)
  358.  
  359.     Applications can use this for critical timing  (granularity of less than
  360.     one second) or to set up code  (such as a watchdog)  that is executed on
  361.     every timer tick. See function 16h (add/delete function from timer tick)
  362.     for the preferred way of actually installing such code.
  363.  
  364.  
  365.     AH = 08h    Flush output buffer
  366.  
  367.             Parameters:
  368.                 Entry:  DX = Port number
  369.                 Exit:   None
  370.  
  371.     This is used to force any pending output.   It does not return until all
  372.     pending output has been sent.  You should use this call with care.  Flow
  373.     control  (documented below)  can make your system hang on this call in a
  374.     tight uninterruptible loop under the right circumstances.
  375.  
  376.  
  377.     AH = 09h    Purge output buffer
  378.  
  379.             Parameters:
  380.                 Entry:  DX = Port number
  381.                 Exit:   None
  382.  
  383.     This is used to purge any pending output.   Any output data remaining in
  384.     the output buffer (not transmitted yet) is discarded.
  385.  
  386.  
  387.     AH = 0Ah    Purge input buffer
  388.  
  389.             Parameters:
  390.                 Entry:  DX = Port number
  391.                 Exit:   None
  392.  
  393.     This is used to purge any pending input.   Any input data which is still
  394.     in the buffer is discarded.
  395.  
  396. Fundamentals of FOSSIL implementation and use                         Page 8
  397. Communications functions
  398.  
  399.  
  400.     AH = 0Bh    Transmit no wait
  401.  
  402.             Parameters:
  403.                 Entry:  DX = Port number
  404.                 Exit:   AX = 0001h - Character was accepted
  405.                            = 0000h - Character was not accepted
  406.  
  407.     This is exactly the same as the "regular"  transmit call, except that if
  408.     the driver is  unable to  buffer the character  (the buffer is full),  a
  409.     value of 0000h is returned in AX. If the driver accepts the character
  410.     (room is available),  0001h is returned in AX.
  411.  
  412.  
  413.     AH = 0Ch    Non-destructive read-ahead
  414.  
  415.             Parameters:
  416.                 Entry:  DX = Port number
  417.                 Exit:   AH = 00h           - Character is
  418.                         AL = Next character    available
  419.                         AX = FFFFh         - Character is not available
  420.  
  421.     Return in AL the next character in the receive buffer.  If the receive
  422.     buffer is empty,  return  FFFFh.  The  character  returned  remains in
  423.     the receive buffer. Some applications call this "peek".
  424.  
  425.  
  426.     AH = 0Dh    Keyboard read without wait
  427.  
  428.             Parameters:
  429.                 Entry:  None
  430.                 Exit:   AX = IBM-style scan code (Character available)
  431.                            = FFFFh               (Character not available)
  432.  
  433.     Return in  AX the  next character  (non-destructive read ahead)  from the
  434.     keyboard; if nothing is currently in the keyboard buffer, return FFFFh in
  435.     AX.   Use IBM-style  function  key mapping  in the high order byte.  Scan
  436.     codes for non-"function" keys  are not specifically required,  but may be
  437.     included. Function keys return 00h in AL and the "scan code" in AH.
  438.  
  439.  
  440.     AH = 0Eh    Keyboard read with wait
  441.  
  442.             Parameters:
  443.                 Entry:  None
  444.                 Exit:   AX = IBM-style scan code
  445.  
  446.     Return in AX the next character from the keyboard;  wait if no character
  447.     is available. Keyboard mapping should be the same as function 0Dh.
  448.  
  449. Fundamentals of FOSSIL implementation and use                         Page 9
  450. Communications functions
  451.  
  452.  
  453.     AH = 0Fh    Enable or disable flow control
  454.  
  455.             Parameters:
  456.                 Entry:  AL = Bit mask describing requested flow control
  457.                         DX = Port number
  458.                 Exit:   None
  459.  
  460.     TRANSMIT flow control allows the "other end" to restrain the transmitter
  461.     when you are  over-running it.  RECEIVE flow control tells the FOSSIL to
  462.     attempt to do just that if it is being overwhelmed.
  463.  
  464.     Two kinds of basic flow control are supported:
  465.  
  466.                 Bit 0 = 1       Xon/Xoff on transmit
  467.                 Bit 1 = 1       CTS/RTS (CTS on transmit, RTS on receive)
  468.                 Bit 2           Reserved
  469. |               Bit 3 = 1       Xon/Xoff on Receive
  470.  
  471.     Flow control is enabled, or disabled, by setting the appropriate bits in
  472.     AL  for the types of flow control we want to ENABLE (value = 1),  and/or
  473.     DISABLE  (value = 0),  and calling this function.  Bit 2 is reserved for
  474.     DSR/DTR,  but is not currently supported in any implementation.
  475.  
  476.     Enabling  transmit  Xon/Xoff will cause the FOSSIL  to stop transmitting
  477.     upon receiving an Xoff.  The FOSSIL will resume transmitting when an Xon
  478.     is received.
  479.  
  480.     Enabling CTS/RTS will cause the FOSSIL to cease transmitting when CTS is
  481.     lowered.  Transmission will resume  when CTS is raised.  The FOSSIL will
  482.     drop RTS when the receive buffer reaches a predetermined percentage full
  483.     The FOSSIL will  raise RTS  when the  receive buffer  empties below  the
  484.     predetermined  percentage full.  The  point(s)  at which  this occurs is
  485.     left to the individual FOSSIL implementor.
  486.  
  487. |   Enabling receive  Xon/Xoff will cause the FOSSIL to send a Xoff when the
  488. |   receive buffer reaches a pre-determined percentage full.  An Xon will be
  489. |   sent when the receive buffer empties below the pre-determined percentage
  490. |   full. The point(s) at which this occurs is left to the individual FOSSIL
  491. |   implementor.
  492.  
  493.     Applications  using this  function  should set all bits  ON  in the high
  494.     nibble of AL as well.  There is a compatible  (but not identical) FOSSIL
  495.     driver implementation that uses the  high nibble as a control mask.   If
  496.     your application sets the high nibble to all ones,  it will always work,
  497.     regardless of the method used by any given driver.
  498.  
  499. Fundamentals of FOSSIL implementation and use                        Page 10
  500. Communications functions
  501.  
  502.  
  503.     AH = 10h    Extended Control-C / Control-K checking and transmit on/off
  504.  
  505.             Parameters:
  506.                 Entry:  AL = Bit mask (see below)
  507.                         DX = Port number
  508.                 Exit:   AX = 0001h - Control-C/K has been received
  509.                            = 0000h - Control-C/K has not been received
  510.  
  511.     This is used for BBS  operation,  primarily.  A bit mask is passed in AL
  512.     with the following flags:
  513.  
  514.                 Bit 0   Enable/disable Control-C / Control-K checking
  515.                 Bit 1   Disable/enable the transmitter
  516.  
  517.     The Enable (bit 0 = 1) and Disable (Bit 0 = 0) Control-C/Control-K check
  518.     function is meant primarily for BBS use. When the checking is enabled, a
  519.     Control-C or Control-K received  from the communications port will set a
  520.     flag internal to the FOSSIL driver,  but will not be stored in the input
  521.     buffer. The next use of this function will return the value of this flag
  522.     in register AX then clear the flag for the next occurrence. The returned
  523.     value is used by the BBS  software to determine whether output should be
  524.     halted or not.
  525.  
  526.     The Disable (Bit 1 = 1) and Enable (Bit 1 = 0) Transmitter function lets
  527.     the application restrain the asynchronous driver from output in much the
  528.     same way as XON/XOFF would.
  529.  
  530.  
  531.     AH = 11h    Set current cursor location.
  532.  
  533.             Parameters:
  534.                 Entry:  DH = Row (line)
  535.                         DL = Column
  536.                 Exit:   None
  537.  
  538.     This function looks exactly like like INT 10h, subfunction 2, on the IBM
  539.     PC. The cursor location is passed in DX: row in DH and column in DL. The
  540.     function treats the screen as a coordinate  system whose origin (0,0) is
  541.     the upper left hand corner of the screen.
  542.  
  543.  
  544.     AH = 12h    Read current cursor location.
  545.  
  546.             Parameters:
  547.                 Entry:  None
  548.                 Exit:   DH = Row (line)
  549.                         DL = Column
  550.  
  551.     Looks exactly like INT 10h,  subfunction 3,  on the IBM PC.  The current
  552.     cursor location  (using the same coordinate  system as  function 16h) is
  553.     passed back in DX.
  554.  
  555. Fundamentals of FOSSIL implementation and use                        Page 11
  556. Communications functions
  557.  
  558.  
  559.     AH = 13h    Single character ANSI write to screen.
  560.  
  561.             Parameters:
  562.                 Entry:  AL = Character to display
  563.                 Exit:   None
  564.  
  565.     The character in AL is sent to the screen by the fastest method possible
  566.     that allows ANSI processing to occur (if available). This routine should
  567.     not be used in such a way that DOS output  (which is not re-entrant) can
  568.     not be employed by some FOSSIL driver to perform the function  (in fact,
  569.     on the IBM PC that is likely to be how it's done).  On some systems such
  570.     as the DEC Rainbow this will be a very fast method of screen writing.
  571.  
  572.  
  573.     AH = 14h    Enable or disable watchdog processing
  574.  
  575.             Parameters:
  576.                 Entry:  AL = 01h - Enable watchdog
  577.                            = 00h - Disable watchdog
  578.                         DX = Port number
  579.                 Exit:   None
  580.  
  581.     When watchdog is enabled,   the state of the carrier detect (CD) line on
  582.     the comm port specified in DX should be constantly monitored. Should the
  583.     state of that line become FALSE (carrier lost), the system should be re-
  584.     booted, to enable the BBS (or other application) to start up again. This
  585.     monitor is not affected by Init/Uninit etc.
  586.  
  587.  
  588.     AH = 15h    Write character to screen using BIOS support routines
  589.  
  590.             Parameters:
  591.                 Entry:  AL = Character to display
  592.                 Exit:   None
  593.  
  594.     The character in AL is sent to the screen using  BIOS-level Input/Output
  595.     routines. This differs from function 13h in that DOS I/O CAN NOT be used,
  596.     as this function might be called from driver level.
  597.  
  598. Fundamentals of FOSSIL implementation and use                        Page 12
  599. Communications functions
  600.  
  601.  
  602.     AH = 16h    Insert or delete a function from the timer tick chain
  603.  
  604.             Parameter:
  605.                 Entry:  AL = 01h - Add a function
  606.                            = 00h - Delete a function
  607. |                       ES = Segment of function
  608.                         DX = Offset of function
  609.                 Exit:   AX = 0000h - Operation successful
  610.                            = FFFFh - Operation unsuccessful
  611.  
  612.     This function is used to allow a  central authority  to manage the timer
  613.     interrupts, so that as code is loaded and unloaded, the integrity of the
  614.     "chain" is not compromised.  Rather than using the traditional method of
  615.     saving the old contents of the timer vector, storing the address of your
  616.     routine there,  and executing a far call to the "old" routine when yours
  617.     is done, instead you call this function. It manages a list of such entry
  618.     points and calls them on a timer tick (interrupt) using a FAR call.  All
  619.     the usual cautions about making DOS calls apply (that is, DON'T!).
  620.  
  621.     This makes it possible for a program to get in and out of the tick chain
  622.     without having to know whether another program has also done so since it
  623.     first insinuated itself.   At least 4 entries should be available in the
  624.     driver's table (including one to be used by Watchdog if implemented that
  625.     way).
  626.  
  627.  
  628.     AH = 17h    Reboot system
  629.  
  630.             Parameters:
  631.                 Entry:  AL = 00h - "Cold boot"
  632.                            = 01h - "Warm boot"
  633.  
  634.     Perform the old 3-finger salute.  Used in extreme emergency by code that
  635.     can't seem to find a "clean" way out of the trouble it has gotten itself
  636.     into.  Hopefully it won't happen while you're computing something in the
  637.     other half of a DoubleDOS system. If your machine can make a distinction
  638.     between a "cold" (power-up, self-test and boot) and a "warm" (just boot)
  639.     bootstrap,  your FOSSIL should support the flag in AL. Otherwise just do
  640.     whatever bootstrap is possible.
  641.  
  642. Fundamentals of FOSSIL implementation and use                        Page 13
  643. Communications functions
  644.  
  645.  
  646. |   AH = 18h    Read block (transfer from FOSSIL to user buffer)
  647.  
  648. |           Parameters:
  649. |               Entry:  CX = Maximum number of characters to transfer
  650. |                       DX = Port number
  651. |                       ES = Segment of user buffer
  652. |                       DI = Offset into ES of user buffer
  653. |               Exit:   AX = Number of characters actually transferred
  654.  
  655. |   A "no-wait"  block read of 0 to FFFFh characters from the FOSSIL inbound
  656. |   ring buffer to the calling routine's buffer. ES:DI are left unchanged by
  657. |   the call; the count of bytes actually transferred will be returned in AX.
  658.  
  659.  
  660. |   AH = 19h    Write block (transfer from user buffer to FOSSIL)
  661.  
  662. |           Parameters:
  663. |               Entry:  CX = Maximum number of characters to transfer
  664. |                       DX = Port number
  665. |                       ES = Segment of user buffer
  666. |                       DI = Offset into ES of user buffer
  667. |               Exit:   AX = Number of characters actually transferred
  668.  
  669.  
  670. |   A  "no-wait"  block  move of 0  to FFFFh  characters  from  the  calling
  671. |   program's  buffer into  the  FOSSIL outbound ring buffer. ES:DI are left
  672. |   unchanged by the call;  the count of bytes actually transferred  will be
  673. |   returned in AX.
  674.  
  675.  
  676. |   AH = 1Ah    Break begin or end
  677.  
  678. |           Parameters:
  679. |               Entry:  AL = 01h - Start sending 'break'
  680.                            = 00h - Stop sending 'break'
  681. |                       DX = port number
  682. |               Exit:   None
  683.  
  684. |   Send a break signal to the modem. If AL=01h the driver will commence the
  685. |   transmission of a break.  If AL=00h the driver will end the break.  This
  686. |   is useful for communications with devices that can only go into 'command
  687. |   mode' when a BREAK is received. Note: the application is responsible for
  688. |   the timing of the BREAK.  Also,  if the FOSSIL has been restrained by an
  689. |   Xoff received from the modem, the flag will be cleared.   An Init or Un-
  690. |   Init will stop an in-progress BREAK.
  691.  
  692. Fundamentals of FOSSIL implementation and use                        Page 14
  693. Communications functions
  694.  
  695.  
  696. |   AH = 1Bh    Return information about the driver
  697.  
  698. |           Parameters:
  699. |               Entry:  CX = Size of user info buffer in bytes
  700. |                       DX = Port number
  701. |                       ES = Segment of user info buffer
  702. |                       DI = Offset into ES of user info buffer
  703. |               Exit:   AX = Number of bytes actually transferred
  704.  
  705. |   Transfer information about the driver and its current status to the user
  706. |   for use in determining,  at the application level, limits of the driver.
  707. |   Designed to assist  "generic" applications  to adjust to "foreign" gear.
  708.  
  709. |   The data structure currently returned by the driver is as follows (sorry
  710. |   but you'll have to live with assembly syntax):
  711.  
  712. |       info    equ     $               ; define begin of structure
  713. |       strsiz  dw      info_size       ; size of the structure in bytes
  714. |       majver  db      curr_fossil     ; FOSSIL spec driver conforms to
  715. |       minver  db      curr_rev        ; rev level of this specific driver
  716. |       ident   dd      id_string       ; "FAR" pointer to ASCII ID string
  717. |       ibufr   dw      ibsize          ; size of the input buffer (bytes)
  718. |       ifree   dw      ?               ; number of bytes left in buffer
  719. |       obufr   dw      obsize          ; size of the output buffer (bytes)
  720. |       ofree   dw      ?               ; number of bytes left in the buffer
  721. |       swidth  db      screen_width    ; width of screen on this adapter
  722. |       sheight db      screen_height   ; height of screen    "     "
  723. |       baud    db      ?               ; ACTUAL baud rate, computer to modem
  724. |       info_size equ $-info
  725.  
  726. |   The ident string should be  null-terminated,  and NOT contain a newline.
  727. |   The baud rate byte contains the bits that  Function 00h would use to set
  728. |   the port to that speed.
  729.  
  730. |   The fields related to a particular port (buffer size,  space left in the
  731. |   buffer,  baud rate) will be undefined if port FFh  or an invalid port is
  732. |   contained in DX.
  733.  
  734. |   Additional information will always be passed after these,  so that,  for
  735. |   example, offset "sheight" will never change with FOSSIL revision changes.
  736.  
  737. Fundamentals of FOSSIL implementation and use                        Page 15
  738. "Layered Application" services
  739.  
  740.  
  741.  
  742. |   The functions below are not necessarily FOSSIL related. However, because
  743. |   dispatchers  that support them are hooked on Interrupt 14H,  it behooves
  744. |   the FOSSIL developer to support them as well to avoid fragmenting memory
  745. |   with several dispatchers.
  746.  
  747.  
  748.  
  749. |   AH = 7Eh    Install an "external application" function
  750.  
  751. |           Parameters:
  752. |               Entry:  AL = Code assigned to external application
  753. |                       DX = Offset of application entry point
  754. |                       ES = Segment of application entry point
  755. |               Exit:   AX = 1954h
  756. |                       BL = Code assigned to application (same as input AL)
  757. |                       BH = 01h - Installation was successful
  758. |                          = 00h - Installation failed
  759.  
  760. |   This call is used by external application code  (special screen drivers,
  761. |   modem code, database code, etc) to link into the INT 14h service for use
  762. |   by multiple applications. The "error return" (BH=0 with AX=1954h) should
  763. |   mean that  another application layer has  already been installed at that
  764. |   particular code. Codes 80h through BFh should be supported.
  765.  
  766. |   External application codes 80h-83h are  reserved by FOSSIL developers for
  767. |   re-organizing FOSSIL services by type (comm, screen, keyboard, system).
  768.  
  769. |   Installed application code will be entered, via a FAR call, from the INT
  770. |   14H dispatcher whenever it is entered with AH=(application code).
  771.  
  772. |   If the value returned in AX from this function is not 1954h, the service
  773. |   code that is trying to be installed should bring up its own INT 14h code
  774. |   that can service INT 14h functions 7h-BFh (80h-BFh are "applications").
  775.  
  776.  
  777. |   AH = 7Fh    Remove an "external application" function
  778.  
  779. |           Parameters:
  780. |               Entry:  AL = Code assigned to external application
  781. |                       DX = Offset of application entry point
  782. |                       ES = Segment of application entry point
  783. |               Exit:   AX = 1954h
  784. |                       BL = Code assigned to application (same as input AL)
  785. |                       BH = 01h - Removal was successful
  786. |                          = 00h - Removal failed
  787.  
  788. |   Removes an application's entry into the table.  Usually so it can remove
  789. |   itself from memory. Error return means ES:DX did not match or that there
  790. |   is no entry at the slot described by AL.
  791.  
  792. |   An application that wants to remove itself from memory can issue the  7F
  793. |   function to remove itself from the table, then, if it is successful, get
  794. |   out of memory. If it had to install itself with an INT 14h dispatcher it
  795. |   may back itself out, provided no other applications  have been installed
  796. |   on top of it (using its dispatcher).
  797.  
  798.  
  799. Fundamentals of FOSSIL implementation and use                        Page 16
  800.  
  801.  
  802.  
  803.  
  804. E.  Validation Suite.
  805.  
  806.     Well, there is one, but it's involved.   Here is a list of software that
  807.     is known to use FOSSIL calls,  and the range of calls used by that
  808.     software:
  809.  
  810.         Software package                        Fossil calls used
  811.  
  812.     Fido,  V11w,  generic version                  00h - 07h
  813.     SEAdog,  V4.1b                                 00h - 0Eh
  814.     Opus,  V1.03a                                  00h - 17h
  815.     BinkleyTerm,  V1.30                            00h - 1Bh
  816.  
  817.     While  there is  certainly no  guarantee that your FOSSIL is bug-free if
  818.     all the above software runs  with it,  you  have probably  done as  much
  819.     as you  can in  a test environment if your FOSSIL is tested with each of
  820.     these packages.
  821.  
  822.  
  823.  
  824.  F. Technical Discussion.
  825.  
  826.     A FOSSIL echomail conference exists,  for the purpose of exchanging info
  827.     and implementation details for FOSSIL drivers.  It is coordinated by Ray
  828.     Gwinn at FidoNet node 1:109/639.  Contact him for details on how to join.
  829.     Keep in mind though,  that this conference is intended  SPECIFICALLY for
  830.     implementors of FOSSIL  software and not as a general Q&A conference for
  831.     people who think FOSSILs have something to do with paleontology.
  832.  
  833.  
  834.  
  835. G. Distribution Of This Document.
  836.  
  837.    This document may be distribute freely as long as it is  not  modified in
  838.    any  way.  Please  list  all  changes  and  deviations  in a given FOSSIL
  839.    implementation in an addendum contained in a  separate file added  to the
  840.    FOSSIL archive.   Also,  please  do  not distribute this document without
  841.    the accompanying version of FOSSIL.CHT.   This will help avoid confusion,
  842.    among both FOSSIL implementors and application developers.
  843.